import { Callout } from 'nextra/components';

# Runtimes in details

<Callout type="warning">
    This section is only useful if you want to learn more, or if you want to use Bref with another deployment tool than Serverless Framework.

    You can skip it for now if you just want to get started with Bref.
</Callout>

## AWS Lambda layers

Bref runtimes are distributed as [AWS Lambda layers](https://docs.aws.amazon.com/lambda/latest/dg/configuration-layers.html). While Bref provides a Serverless plugin to simplify how to use them, you can use the layers directly.

The layer names (aka "[ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)") follow this pattern:

```
arn:aws:lambda:<region>:534081306603:layer:<layer-name>:<layer-version>
```

For example:
```
arn:aws:lambda:us-east-1:534081306603:layer:php-80:21
```

You can use layers via their full ARN, for example in `serverless.yml`:

```yml filename="serverless.yml" {9}
service: app
provider:
    name: aws
functions:
    hello:
        # ...
        runtime: provided.al2
        layers:
            - 'arn:aws:lambda:us-east-1:534081306603:layer:php-80:21'
```

Or if you are using [SAM's `template.yaml`](https://aws.amazon.com/serverless/sam/):

```yml filename="template.yml"
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
    Hello:
        Type: AWS::Serverless::Function
        Properties:
            # ...
            Runtime: provided.al2
            Layers:
                - 'arn:aws:lambda:us-east-1:534081306603:layer:php-80:21'
```

Bref layers work with AWS Lambda regardless of the tool you use to deploy your application: Serverless, SAM, CloudFormation, Terraform, AWS CDK, etc.

<Callout>
    Remember: the layer ARN contains a region. **You need to use the same region as the rest of your application** else Lambda will not find the layer.
</Callout>

## Layer versions

All the layer/runtime versions can be found at [**runtimes.bref.sh**](https://runtimes.bref.sh/).

Here are the latest versions:

<iframe src="https://runtimes.bref.sh/embedded" class="w-full h-96"></iframe>

You can also find the appropriate ARN/version for your current Bref version by running:

```bash
serverless bref:layers
```

<Callout type="warning">
    If you use a layer ARN directly, you will need to update the ARN regularly (the `version` part).
</Callout>

### Layers NPM package

You can use [the `@bref.sh/layers.js` NPM package](https://github.com/brefphp/layers.js) to get up-to-date layer ARNs in Node applications, for example with the AWS CDK.

## Telemetry ping

Bref layers send an anonymous ping to estimate the total number of Lambda invocations powered by Bref. That statistic is useful in two ways:

- to provide new users an idea on how much Bref is used in production
- to communicate to AWS how much Bref is used and push for better PHP integration with AWS Lambda tooling

We consider this to be beneficial both to the Bref project (to get more users and more consideration from AWS) and for Bref users (more users means a larger community, a stronger and more active project, as well as more features from AWS).

So far, knowing the number of Bref invocations has helped Bref grow, be recognized by AWS, and opened a lot of doors.

### Data

You can find the latest number of AWS Lambda invocations on the [Bref homepage](https://bref.sh/).

On the month of the Bref 1.0 release, [Bref was powering 1 billion invocations per month](../../news/01-bref-1.0.md#1-billion-executions-per-month).

On the month of the Bref 2.0 release, [Bref was powering 10 billion invocations per month](../../news/02-bref-2.0.md).

### What is sent

The data sent in the ping is completely anonymous. It does not contain any identifiable data about anything (the project, users, etc.).

**The only data it contains is:** A Bref invocation happened with the layer XYZ (where XYZ is the name of the Bref layer, like "function", "fpm" or "console") and whether the invocation was a cold start.

Here is an example payload:

```
Invocations_100:1|c\nLayer_fpm_100:1|c\nCold_100:1\nWarm_100:0|c
```

Anyone can inspect the code and the data sent by checking the [`Bref\Runtime\LambdaRuntime::ping()` function](https://github.com/brefphp/bref/blob/master/src/Runtime/LambdaRuntime.php#L387).

### How is it sent

The data is sent via the [statsd](https://github.com/statsd/statsd) protocol, over [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol).

Unlike TCP, UDP does not check that the message correctly arrived to the server.
It doesn't even establish a connection. That means that **UDP is extremely fast**:
the data is sent over the network and the code moves on to the next line.
When actually sending data, the overhead of that ping takes about 150 micro-seconds.

However, this function actually sends data every 100 invocation, because we don't
need to measure *all* invocations. We only need an approximation.
That means that 99% of the time, no data is sent, and the function takes 30 micro-seconds.
If we average all executions, the overhead of that ping is about **31 micro-seconds**.

Given that it is much much less than even 1 milli-second, we consider that overhead negligible.

### Disabling

The ping can be disabled by setting a `BREF_PING_DISABLE` environment variable to `1`.

<Callout>
    If your company policy requires disabling the ping, it would be extremely beneficial to the project (and transitively to your company) to report privately a rough number of invocations. You can send me a direct email at [matthieu@bref.sh](mailto:matthieu@bref.sh).

    Such data is collected privately and is not shared publicly on its own. I include it in the total number of invocations that I share publicly.
</Callout>
